---
title: SAIF.Business.Utilities architecture
summary: Architectural responsibilities, boundaries, and interaction patterns for the text-formatting utility library.
status: draft
owner: SAIF Documentation Generation
last_reviewed: 2026-08-21
library: SAIF.Business.Utilities
reference_type: embedded
---

# SAIF.Business.Utilities architecture

SAIF.Business.Utilities is a narrow, stateless, leaf-level text-formatting utility library. It has no BOF business-object lifecycle, no persistence, and no UI involvement; its entire public surface converts raw stored text (typically all-caps names, addresses, or statuses) into human-readable mixed case, and converts numeric amounts into English word form.

## Responsibilities
- Convert all-caps or inconsistently cased stored strings into human-readable "title case" via `TitleCase.ToTitleCase` and the `.ToTitleCase()` string extension.
- Provide additional string-shaping extension helpers (`.ToProperCase()`, `.ToPadCapitalLetters()`, `.ToLower()`/`.ToUpper()` for string arrays, `.ContainsOnlyNumericCharacters()`).
- Spell out numeric (`Long`) values as English words via `mdlTextConversion.NumberToText`, for amount-in-words style rendering.
- Provide a simple sentence-case transform via `.ToSentenceCase()`.

## Component boundaries
- `TitleCase` (Public Class, all members `Shared`): owns the title-casing algorithm — tokenization, per-token case classification against curated word lists, delimiter-preserving reassembly, and possessive-suffix handling.
- `TitleCaseExtensions` (Public Module): exposes `TitleCase.ToTitleCase` and related string helpers as `.ToXxx()` extension methods callable directly on `String`/`String()` instances; a thin surface adapter, not an independent responsibility.
- `mdlTextConversion` (Public Module): owns numeric-to-English-words conversion (`NumberToText`) and the unrelated `ToSentenceCase` extension.
- No component in this library performs data access, participates in `IDataPortalInfo`/`ProcessPortalRequest` flows, or holds mutable instance state — every public entry point is a `Shared`/`Module`-level pure function operating only on its string/numeric input.

## Interaction model
- The library has zero outbound project dependencies of its own (no `<ProjectReference>` entries in `SAIF.Business.Utilities.vbproj`); all dependency flow is inbound (fan-in), consistent with a shared, foundation-level utility package.
- It is consumed by higher business-layer libraries — confirmed call sites in `SAIF.Business.Policy.Agency\clsAgency.vb` (`Name` property) and `SAIF.Business.View.Policy\Associations\clsPolicyAssociation.vb` (`PolicyName`, `PolicyStatusDescription` properties) — which call `.ToTitleCase()` to format display-name values sourced from Oracle-backed business data.
- `SAIF.Application.Policy\PolicyHeader\clsStandardPolicyHeaderDataProvider.vb` holds a project/assembly reference to this library, but no direct call site to `ToTitleCase`/`ToSentenceCase`/`NumberToText` was confirmed in that file; the exact member used there is unconfirmed.**
- Internally, `ToTitleCase` follows a tokenize → classify → reassemble → suffix-correction → first-letter-force pipeline: it splits input on non-word/non-digit boundaries via `Regex.Split`, title-cases each token against static word lists, reassembles tokens with original delimiters preserved via a recursive `ReassembleString` helper, re-applies an exact-suffix pass for possessive `'s` handling, then forces the first output character to upper case.
- `NumberToText` follows a magnitude-based recursive decomposition (ones/teens → tens → hundreds → thousands/millions/billions/trillions), each level delegating to the private `RoundDown` helper for integer floor-division.

## Design constraints
- Title-casing exception vocabulary (all-caps abbreviations, mixed-case exceptions, connector words, name prefixes/suffixes, ordinal suffixes) is governed entirely by static, hard-coded `Shared` word lists rather than external configuration or database lookup — extending the vocabulary requires a code change and rebuild, not a config change.*
- `NumberToText` enforces an upper bound of 999,999,999,999,999 and throws `ApplicationException` beyond that value.
- The great majority of packages declared in `SAIF.Business.Utilities.vbproj` (the SAIF BOF Framework set, `SAIF.Framework.Common`, `SAIF.HashUtil`, `SAIF.Web.API.Clients`/`Core`, `Oracle.ManagedDataAccess`, `Newtonsoft.Json`, `RestSharp`) are unused by this library's two-file source surface and appear to be inherited from a shared project template rather than reflecting real functional dependencies.* Only `System.Text` / `System.Text.RegularExpressions` (BCL) are demonstrably exercised by the code.
- No SAIF BOF Framework base-class inheritance is present (frameworkDensity = 0); this library does not participate in the BOF data-portal lifecycle.

## Architecture diagram
The following diagram shows this library's leaf position and its fan-in consumers.

```mermaid
flowchart TD
	A[SAIF.Business.Policy.Agency<br>clsAgency] --> U[SAIF.Business.Utilities]
	B[SAIF.Business.View.Policy<br>clsPolicyAssociation] --> U
	C[SAIF.Application.Policy<br>clsStandardPolicyHeaderDataProvider] --> U
	U --> T[TitleCase /<br>TitleCaseExtensions]
	U --> M[mdlTextConversion]
```

## Sequence diagram
The following diagram shows a typical title-casing call from a consumer property.

```mermaid
sequenceDiagram
	participant Consumer as clsAgency.Name
	participant Ext as TitleCaseExtensions
	participant TC as TitleCase
	Consumer->>Ext: m_AgencyName.ToTitleCase()
	Ext->>TC: ToTitleCase(inString)
	TC->>TC: Regex.Split into tokens
	TC->>TC: TitleCaseSingleWord per token
	TC->>TC: ReassembleString with original delimiters
	TC->>TC: ApplyExactSuffixList
	TC-->>Ext: title-cased string
	Ext-->>Consumer: formatted display name
```

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Configuration settings](configuration.md)
- [API reference](api/index.md)

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- SAIF.Business.Utilities\SAIF.Business.Utilities.vbproj
- SAIF.Business.Utilities\TitleCase.vb
- SAIF.Business.Utilities\mdlTextConversion.vb
- SAIF.Business.Policy.Agency\clsAgency.vb
- SAIF.Business.View.Policy\Associations\clsPolicyAssociation.vb
- SAIF.Application.Policy\PolicyHeader\clsStandardPolicyHeaderDataProvider.vb
- .saifdocgen/state/runs/20260821-113120-claims-bof-web-legal/analysis/TSK007-analysis.md